Plus Porter Version 1.0.0.1

PLUS PORTER
------------
Plus porter is an application that facilitates porting mods of the freeware PC game Cave Story to its
commercial counterpart, Cave Story+. The program works by letting the user gather all the modified
resources, and packages them into a patch that can be applied to an installation of Cave Story+. While
one could do most of this maually, Plus Porter makes this task quicker and easier, and there are some things
that can NOT be done manually but are made possible with Plus Porter, such as being able to legally
distribute mods with partially edited spritesheets while maintaining double resolution all throughout.


GENERAL USAGE NOTES
--------------------

- Usage of this program requires that you have a copy of Cave Story+ on your hard drive. This program may
not perform as intended if the base files of your installation of Cave Story+ have been modified.

- I take no responsibility for any damage this program may do to your computer or to your installation of Cave
Story+. Use at your own risk. It is recommended that you use this program with a backup copy of the game,
especially given that this program is currently in alpha stage.


COMPATIBILITY
--------------
This program should work on any Windows operating system XP and later.
It has not been tested on any other OS.
Windows XP users should downgrade to a Java 7 update prior to April 2014, as updates beyond that point do not
support Windows XP and cause known performance issues with this program.


SETTING UP
-----------
There are two purposes Plus Porter serves: making ports, and applying ports
Before you can start using this program, however, you first must have a valid Cave Story+ directory to
reference to. To set this up, go to "File" -> "Open CS+ directory", and select the executable file located
in a valid Cave Story+ installation. If the installation has been successfully verified, you will be able to
access all the tools of Plus Porter. After you've done this once, the program will automatically open up the
last opened CS+ directory every subsequent time you launch the program. You can turn this check off in
preferences if you want to, though.


HOW TO APPLY PORTS
-------------------
To apply a port that has already been made, go to "File" -> "Open port...", browse to the folder of the
port you wish to open, and click "Open." After the port has been loaded, go to "File" -> "Apply port", and a
window will open up listing all mods currently installed in that game of CS+, and the order in which they'll
be listed in the challenge menu (with the one at the top appearing on the main menu). You are able to
arrange the mods in whatever order you want the challenge menu to list them, and then click the
"Apply port!" button to apply the port to your Cave Story+ installation. Exit out of plus porter, and you'll
now be able to experience the mod in Cave Story+.


HOW TO MAKE PORTS
------------------
Before porting a mod, it should be noted that there are some prerequisites for a mod to be CS+ compatible:

- The only hex edits that can be carried over are the weapon data, the wave data for playing music, and the
map data

- The mod may not have any more than 95 maps.

- The mod may not have any ASM hacks


To begin a new port, go to to "File" -> "New port...", and a window will pop up letting you set some basic
properties for your port. The port name will decide what name is shown when selecting your mod from the
challenge menu in Cave Story+, the folder name will define the name of the folder your port will be saved in,
and the description can include a quick blurb about your mod, although this field is not mandatory. If the
"Enable save slots" checkbox is checked, then you will be presented with three save slots when selecting
your mod. If it is left unchecked, then your mod will behave as a timed challenge. The requirement field
determines what you must do when playing the regular story mode in order to unlock the mod. If you want to
come back and edit these properties later, you may do so by going to "Settings" -> "Port Properties"

The first thing I recommend doing after that is importing the stage folder. To do this, go to "Edit" ->
"Replace" -> "Stage folder", and browse to your mod's stage folder. If a game executable is detected, you
will be prompted to import the map data from it in order to generate your mod's stage.tbl file. This will
then import all the maps from your mod.

If necessary, go to "Edit" -> "Replace..." -> "Miscellaneous file", and replace any global scripts, .tbl
files, or other generic files located in the base directory with files changed for your mod. To replace a
file, browse to your replacement file, select the file from the list that you want to replace, and click the
"replace" button. This will set that file to be replaced by the file you've selected. If you want to undo the
replace, you may either click the "cancel" button, or delete the text from the textfield with the replacement
file, and click the replace button while your desired file is selected on the list. When you've verified what
files you want replaced with which ones, click the "Accept" button the apply the changes. The same widget is
used for replacing maps, NPC spritesheets, backgrounds, credit illustrations, miscellaneous images, and music.

If you are replacing an image, then your replacement image will be scanned for any of NICALiS' 2x resolution
graphics, the parts that have it will be removed from the image, and references for where to find them will
be stored in a nearby text document. The NICALiS graphics will be put back into the image when you apply the
port. This is to avoid any copyright infringement, as directly distributing NICALiS' double resolution
graphics is illegal.

If you wish to add new maps, tilesets, credit images, backgrounds, or NPC tilesets without replacing any
existing ones, then click the corresponding add button, or go to "Edit" -> "Add..." -> and select your
desired type of resource. For adding types of resources that have more than one field, it is mandatory that
you fill out both fields as opposed to replacing a resource in which case you can replace only one if you want.

Alternatively, you can do most of this automatically. Simply go to "File" -> "Auto-Port", select an
unmodified Cave Story+ installation, an unmodified freeware Cave Story installation, and a copy of the mod
you wish to port. Click the "Make Port!" button, and it will automatically do everything for you except for
properly replace all spritesheets.


CONTACT
--------
If you wish to contact me, first create an account on the Cave Story Tribute Site forums:
http://www.cavestory.org/forums/index.php

If you wish to make any comments, suggestions, or bug reports, then drop me a line here:
http://www.cavestory.org/forums/index.php?/topic/5338-plus-porter-beta-1000/

If you wish to contact me directly, then message me here:
http://www.cavestory.org/forums/index.php?/user/2705-haydenstudios/


CREDITS
--------
A huge thank you goes to the following people for their contributions to Plus Porter:

-Polaris, for thinking of the name for this program

-ThePotatoWhisperer, for being the only person to report a bug during this program's alpha phase.

-Noxid, for writing the code this program uses for loading mapData from exes, as well as decoding and encoding
tsc files. Saved me lots of time.

-Tpcool, for helping me gain intel on something by testing something in a version of CS+ that I don't have
access to

-I would also like to give an extra special thanks to each and every single person who messaged me, made a
post, or made a comment on a youtube video of mine requesting that Cave Story with a Fourth ending be ported
to Cave Story+. If it weren't for all the requests for a port of my fourth ending mod, then this program
wouldn't have happened. So if you're one of those people reading this, and you enjoy this program, then give
yourself a pat on the back, you have yourself to thank for the fact that this program exists.